feat(packaging): load JavaScript from app.asar and unpack only native files - #647

Stacked on #646 (base: fix/node-pty-unpacked-helper). It aligns the package layout with upstream deepseek-harness apps/desktop.

Why

Since #646, every consumer of the bundled packages runs on the Electron runtime: the main process, the Harness utility process on macOS, and the Helper or executable in Node mode for package commands and shims. That runtime reads app.asar. Unpacking all of node_modules therefore bought nothing, and it caused two problems:

• about 21k loose files, which is the root of the slow Windows installs;
• physical paths containing app.asar, which tripped dependencies' path heuristics (the node-pty app.asar.unpacked.unpacked bug fixed in fix(mac): terminal posix_spawn ENOENT; run package commands on the Electron Helper and drop bundled Node #646).

Changes

• asarUnpack keeps only what the OS loads or executes: native addons and libraries, node-pty spawn-helper, ripgrep, the LibreOffice engine and sherpa-onnx platform packages, and the PPT runtime.
• Runtime root: removed runtimePackageRoot; the bundled runtime root is app.getAppPath() (app.asar when packaged).
• Office engine: build/office-engine-resolution.mjs is adapted from upstream apps/desktop-host/src/office-engine.ts. It resolves @deepseek-ai/libreoffice-kit-<platform>-* to app.asar.unpacked, because libreoffice-kit derives the engine executable from that package's resolved path, and through the archive the executable fails stat/spawn ("executable is not executable"). It is registered in harness-node-entry and is a no-op outside an app.asar layout. Like upstream, it canonicalizes the archive path before the prefix comparison. Otherwise a symlinked or junctioned install, Windows 8.3 names or drive-letter case would leave the engine inside the archive.
• node-pty patch removed: upstream node-pty's own app.asar → app.asar.unpacked mapping is correct in this layout. Upstream relies on the same behaviour.
• afterPack (scripts/after-pack.cjs):
  • verifies the PPT runtime through app.asar on the packaged Helper;
  • new scripts/verify-asar-unpack.cjs fails packaging when a Mach-O, ELF or PE file is packed inline.
• Windows release smoke loads koffi and pnpm through app.asar.
• Docs (release runbook) and tests updated.

Startup stages touched (AGENTS.md table):

• Backend loading: Harness entry and host anchor now point inside app.asar.
• Client discovery: same anchor.
• Both ordinary Profiles and Safe Mode use the installation anchor in app.asar. Profiles and generations hold no links into the installation directory.

Also included: Safe Mode sidebar exit

With blocking compatibility findings, the sidebar "Exit Safe Mode" button reopened the already-open manager and returned, so the click did nothing visible. The manager's own restart button asked for confirmation and exited.

The sidebar button now asks the same question (shared safeModeExitConfirmation). "Exit anyway" leaves Safe Mode; "Manage plugins" opens the manager. When the manager is open and waiting, the exit goes through its restart action.

Checked: unit tests in test/safe-mode.test.ts. Not yet clicked in the real Safe Mode UI with blocking findings.

Checks

• npm test: 180 files / 1606 tests. npm run typecheck and git diff --check pass.
• New regression tests:
  • node-pty-asar-layout spawns a PTY with unpatched node-pty loaded from app.asar and natives in .unpacked;
  • office-engine-resolution resolves the engine on the Electron runtime, with and without the hook, and through a linked install directory;
  • verify-asar-unpack rejects an inline Mach-O and accepts it once unpacked.
• Unsigned package:dev:dir on macOS arm64 passes both afterPack gates. Unpacked files went from 21,212 (549 MB) to 1,596 (235 MB); app.asar is 281 MB.
• The packaged app was run with an isolated userData and HOME:
  • Harness loads from app.asar in the utility process and is ready in about 1.6 s. The UI mounts, including the PPT plugin.
  • The sidebar terminal is interactive: echo returns /bin/zsh arm64 on unpatched node-pty.
  • In a utility process, as Harness runs: node-pty, ripgrep and pnpm work, and LibreOffice converts an ODT to PDF through the asar-loaded worker. The conversion fails without the hook.
  • The .desktop-bin pnpm shim runs the app.asar pnpm.
  • The main process installed a real generation using the installer and pnpm from app.asar.
  • Safe Mode starts: Harness is ready from the installation anchor and the UI mounts.

Not verified

• Windows packaging and installer, including install time and file count. Also unverified there: the koffi directory-picker worker loading from app.asar, which the CI smoke does not cover.
• x64 macOS, a signed and notarized build.
• Market install of a plugin through the real UI, a local symlinked plugin, and an upgrade from an installed previous release.

🤖 Generated with Claude Code